fix(init): gate unsupported --features and tag dry-run runs - #1535

…t) (#1536)

## Problem

`Lint & Typecheck` fails on an internal Biome error, with no real lint
violation in the changed code:

```
src/lib/formatters/output.ts  project  INTERNAL
  ! Biome encountered an unusually large amount of types which exceeded the limit of 200,000.
```

`output.ts` imports valibot's `GenericSchema`, whose recursive generic
graph pushes Biome's project-mode type inference over its 200,000-type
ceiling — the **same internal Biome bug already handled for
`custom-ca.ts`** in this config (see the existing
`"!!src/lib/custom-ca.ts"` force-ignore).

It surfaces **non-deterministically**: `main` passes by a hair, but the
exact type count tips over on PR runners, so unrelated PRs fail this job
identically — e.g. #1499, #1501, and #1535. Re-running does not clear it
(deterministic per branch state).

## Fix

Force-ignore `src/lib/formatters/output.ts` the same way as
`custom-ca.ts`, until Biome raises/fixes the limit.

```jsonc
"!!src/lib/custom-ca.ts",
"!!src/lib/formatters/output.ts"
```

## Verification

`pnpm run lint` (the CI invocation) now passes:

```
Checked 1025 files in 3s. No fixes applied.   (exit 0)
```

Unblocks #1535 (and the other PRs above) once merged. Trade-off is the
same one already accepted for `custom-ca.ts`: `output.ts` (a leaf
formatter) is skipped by Biome; it stays covered by `tsc`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

…, sourcemap auth, stale CONTRIBUTING ref (#1540)

## Documentation Audit Report — 2026-09-07

Weekly audit of the Sentry CLI documentation against the implementation.
Covers all changes since the last audit (PR #1514, merged 2026-08-31).

---

### Changes in This PR

**1. init.md: Remove gated features and add `mcp-observability`**

PR #1535 (`fix(init): gate unsupported --features`) removed `metrics`,
`sourcemaps`, and `attachments` from `SUPPORTED_FEATURE_NAMES` because
their setup isn't fully automated yet. The init fragment still listed
`metrics` and `sourcemaps` as available features. Also,
`mcp-observability` was added as a supported feature but was missing
from the docs.

- **Source:** `src/commands/init.ts` lines 68–77
(`SUPPORTED_FEATURE_NAMES`)
- **Doc file:** `apps/cli-docs/src/fragments/commands/init.md`

**2. explore.md: Add `replays` dataset documentation**

The `sentry explore` command supports five datasets (`errors`, `spans`,
`metrics`, `logs`, `replays`), but the explore fragment had zero
documentation for the `replays` dataset — no examples, no mention in any
dataset listing. Added a Replays example section and a complete Datasets
reference table.

- **Source:** `src/commands/explore.ts` lines 100–106 (`VALID_DATASETS`)
- **Doc file:** `apps/cli-docs/src/fragments/commands/explore.md`

**3. sourcemap.md: Note that `sourcemap inject` runs without
authentication**

PR #1526 (`fix(sourcemap): let inject run without authentication`) set
`auth: false` on the inject command, making it explicit that it's a
purely local file operation. The docs didn't mention this, which is
important for CI pipelines where inject should run before auth.

- **Source:** `src/commands/sourcemap/inject.ts` line 74 (`auth: false`)
- **Doc file:** `apps/cli-docs/src/fragments/commands/sourcemap.md`

**4. CONTRIBUTING.md: Fix stale `sentry config set` reference**

The Context Resolution section referenced `sentry config set`, which was
renamed to `sentry cli defaults` long ago.

- **Source:** `src/commands/cli/defaults.ts` (the actual command)
- **Doc file:** `packages/cli/CONTRIBUTING.md` line 47

---

### Full Gap Report

#### A. Undocumented or Missing Commands/Subcommands

No gaps. All commands have auto-generated doc pages via
`generate-command-docs.ts`, and every route in `src/app.ts` produces a
page under `commands/`. The `groupRoutesByReference()` function creates
an automatic 1:1 mapping.

#### B. Undocumented Flags

No new gaps. All non-hidden flags are auto-generated into the Options
tables by the command doc generator. The only hidden flags
(`src/commands/cli/setup.ts`, `src/commands/bash-hook.ts`) are
intentionally hidden.

#### C. Missing Usage Examples

| Gap | Status |
|-----|--------|
| `sentry explore --dataset replays` — no examples in fragment | **Fixed
in this PR** |

#### D. Stale Descriptions

| Gap | Status |
|-----|--------|
| init.md listed `metrics`, `sourcemaps` as features — removed in PR
#1535 | **Fixed in this PR** |
| init.md missing `mcp-observability` feature — added in same PR |
**Fixed in this PR** |
| CONTRIBUTING.md references `sentry config set` instead of `sentry cli
defaults` | **Fixed in this PR** |

#### E. Missing Route Mappings in Skill Generator

N/A — `ROUTE_TO_REFERENCE` was removed in a prior refactor.
`groupRoutesByReference()` now automatically maps each visible route to
its own reference file.

#### F. Installation / Distribution Gaps

No new gaps since last audit. The install script flags
(`--no-modify-path`, `--no-completions`, `--no-agent-skills`) and env
vars (`SENTRY_INSTALL_DIR`, `SENTRY_VERSION`, `SENTRY_INIT`) are
documented in `getting-started.mdx`. The platform support table is
auto-generated.

#### G. Undocumented Environment Variables

No new gaps. The env registry (`src/lib/env-registry.ts`) has 27
entries, all documented via auto-generation. Previously identified niche
variables (`SENTRY_ENVIRONMENT`, `SENTRY_DIST`,
`SENTRY_CLI_NO_EXIT_TRAP`, `SENTRY_SCAN_DISABLE_WORKERS`, `SENTRY_RN_*`)
remain intentionally excluded as they are internal, test-only, or legacy
bash-hook scoped.

#### H. Auth / Self-Hosted Gaps

No new gaps. The `sourcemap inject` auth-free change (PR #1526) is now
documented.

#### I. Plugin/Skills Gaps

No new gaps since PR #1514. Skills install targets (`~/.claude`,
`~/.agents`), dotagents integration, and the automatic install on
`sentry cli setup` / `sentry cli upgrade` are accurately documented. The
`plugins/README.md` correctly references the current `.claude-plugin`
structure.

#### J. README / DEVELOPMENT.md Drift

| Claim | Status |
|-------|--------|
| README: Node.js 20+, dev 22.15+ | Matches `package.json`
(`engines.node: ">=20.0"`, `devEngines.runtime.version: ">=22.15"`) |
| README: pnpm 10.11+ | Matches `pnpm-workspace.yaml` constraints |
| README: License FSL-1.1-Apache-2.0 | Matches `LICENSE.md` |
| README: Build/test commands | Match `package.json` scripts |
| CONTRIBUTING.md: `sentry config set` | **Fixed in this PR** |

---

### Top 5 Most Impactful Fixes (Prioritized)

1. **init.md feature list stale** — Users/agents running `sentry init
--features metrics` or `sentry init --features sourcemaps` would get a
confusing `Unknown init feature` error. High-impact because init is the
onboarding entry point.

2. **explore replays undocumented** — The entire `replays` dataset was
silently available but had zero documentation. Users and agents had no
way to discover this capability.

3. **sourcemap inject auth note** — CI pipelines commonly run `inject`
before `upload`. Knowing inject doesn't need auth lets pipelines defer
authentication, simplifying pipeline ordering.

4. **CONTRIBUTING.md stale command reference** — Contributors following
the guide would try a non-existent `sentry config set` command.

5. **mcp-observability feature undocumented** — New init feature for
MCP/agent observability was missing from docs, preventing discovery of
this capability.

<div><a
href="https://cursor.com/agents/bc-fee4f405-65bc-4c62-ba8c-8f93d952a974?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>